COMMENT ⊗   VALID 00008 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002	1. Introduction
C00005 00003	2. Command Syntax:
C00008 00004	3. The Format of a Source File:
C00014 00005	4. The Format of a Symbol Definition File:
C00016 00006	5. The Format of an Output File:
C00019 00007	6. A Sample Run:
C00021 00008	7. Known bugs:
C00023 ENDMK
C⊗;
1. Introduction

MICROS (formerly called SYMBOL) is a cross-assembler which lets you
assemble code for a variety of micro-processors.  To date, the
micro-processors that this program knows about are the Zilog Z80, Intel
8080, Motorola 6800, and the MOS Technology 650X.

This program takes a source input file and a 'symbol definition' file,
and produces an output file in an ASCII hex loader format.  It can also
produce a listing file in standard format, or optionally a format suitable
for the CREF (Cross REFerence) program.

The history of this program is unclear.  I believe Andy Moorer imported it
from somewhere.  The original documentation was as sketchy as this
documentation, only somwhat less readable.  At the very bottom was a phone
# for a Bill Weiher at Zilog (I believe he now works at Storage Technology
in Lousville, KY).  I know Bill used to work at SAIL so it is possible
that the program started out here.  Andy Moorer debugged some of it,
and added the COMMENT pseudo-op so that it can read past E directory
pages.

About this documentation:
I haven't really worked with this program enough to really get to know it.
Please add to it, format it, correct it, and make it wonderful as you see
fit. 		- ROB 27-Apr-79
2. Command Syntax:

At the '*' prompt, MICROS is expecting a command line of the form:

<RelFile>[,<LstFile>[/C]]←<SourceFile>(<SymbolSpec>)

<RelFile>  is the name of the file to get the binary output.  If no
	   extension is specified, the default extension '.REL' is
	   used.

<LstFile>  is the name of the file to get the listing output.  If
	   this field is blank, then no listing output is produced.
	   If no extension is specified, the the default extension
	   '.LST' is used.  The '/C' switch will generate a file that
	   can be run through CREF to produce a cross-reference
	   listing (but you can't list it until after it is CREFed).

<SrcFile>  is the name of the source file.  If no extension is
	   specified, MICROS looks for a file with extension '.MIC'.

<SymSpec>  specifies the type of the target microprocessor.  MICROS
	   looks for a 'symbol file' with the name <SymSpec>.SYM, and
	   uses the information there to interpret the meaning of the
	   code in the source file.  (Note that the extension of the
	   symbol file must be '.SYM'.) The default PPN for the symbol
	   file is [1,3].  Currently on [1,3] are the files 8080.SYM,
	   6500.SYM, Z80.SYM, and 6800.SYM.

For example:

*FOO.COD,MUM/C←FOO(8080)

looks for a file named FOO.MIC for input, 8080.SYM[1,3] for a symbol
definition file, and produces binary output in a file named FOO.COD, and a
CREFable listing output in MUM.LST.

3. The Format of a Source File:

For the most part, the assembler accepts FAIL-like syntax and directives.
Conditional assembly, macro definitions, and several pseudo-ops are the
same as in FAIL. Your can write FAIL-like constructs
(but replacing all instances of "←" with "SET").

(Note that this documentation could use a real description of atoms, labels,
symbols, expressions, etc...- ROB 27-Apr-79)

   3.1 Format of a source line:

Like most of your favorite assemblers, the format for a typical line of
source code is:

LABEL:	OP  <args>	; comments

I confess I have not read the code to this program to see exactly how flexible
this format really is.

   3.2 Symbols

The special symbol "." is used to signify the 'current location counter', ie,
the location in memory where the next data is to be stored.  The value of "."
is modified explicitly (via the SET, ORG, PHASE, or DEPHASE directives),
or implicitly (by any operation that outputs code or reserves storage).

*** UNLIKE FAIL **** all numbers are normally in decimal.
To get hex, precede a number with "$" or follow a number with "H".
To get octal, precede with "@", or follow with "O" or "Q"
To get binary, precede with "%" or followed with "B"
Single quotes surrounding text is ASCII for the character, like 'A'

   3.3 Expressions

Expressions are made up from atoms and operators.  Expressions can be nested
using parentheses.

Valid operators are:
	+				-
	*				/
	OR				AND
	!	Same as OR		&	Same as AND
	NOT				XOR
        SHR	Shift right		SHL	Shift left

   3.4 Pseudo-ops

	ORG <n>	Sets absolute program origin.
SYMBOL	EQU <n>	Defines symbol A to have value <n>.  No redefinition
		is allowed. (note no colon between the symbol and the op-code)
SYMBOL	SET <n>	Defines symbol A to have value <n>, but redefinition
		is permitted.  This is good for constructs like
		(A SET A+1).
	DB <b0>,<b1>,<b2>...	Deposits 8-bit data at the current location
		and increments the location counter accordingly.
	DW <w0>,<w1>,<w2>...	Deposits 16-bit data at current location
		and increments the location counter accordingly.
	DS <n>	Reserves <n> 8-bit bytes of storage.  Equivalent to
		(. SET .+<n>)
	COMMENT <chr> <any text except chr> <chr>	The standard
		FAIL-like comment.  Yes, the assembler can eat E directories.
	PHASE	Directs the assembler to start assembling code as if it were
		to be executed starting at location <n>, but directs the loader
		to load the code in-line.
	DEPHASE	Tells the assembler to undo the effect of the previous PHASE
		directive.
	END	Signals the end of the source file.

   3.5 Conditional Assembly

IFG exp<text>	; if <exp> is > 0, then <text> is assembled
IFE exp<text>	; if <exp> is = 0, then <text> is assembled
IFL exp<text>	; if <exp> is < 0, then <text> is assembled
IFN exp<text>	; if <exp> is ≠ 0, then <text> is assembled
IFGE exp<text>	; if <exp> is ≥ 0, then <text> is assembled
IFLE exp<text>	; if <exp> is ≤ 0, then <text> is assembled
IFB exp<text>	; if <exp> is blank (such as a null arg to a macro), then <text>
		  is assembled.
IFNB exp<text>	; if <exp> is non-blank, then <text> is assembled

   3.6 Macros

	DEFINE FOO(A,B,C) <text>	; uses "#" as the concatenation character
	DEFINE FOO@c(A,B,C) <text>	; uses "c" as the concatenation character
	FOR A←				;
	FOR A IN			;
	FOR A INC			; uses character by character (like FAIL ε)


   3.7 Uncategorized junk:

MOS TECHNOLOGY SPECIFIC FORMATS:
  The indirect addressing modes for the MOS TECHNOLOGY are specified like
	JSR	(adr,X)
	JSR	(adr),Y

  Page zero FORWARD references should be preceded by "\", which will
  assemble an absolute address and waste a byte, but will be executed
  correctly.
4. The Format of a Symbol Definition File:

Damned if I know (yet).
			- ROB 19-Apr-79

For each symbol that the assembler will accept, there is a line of the
format:

SYMBOL,a,b,c

The "a" field is the opcode (in octal) for opcode symbols, or the
quantity that gets summed into the opcode field for various registers.

The "b" field is the symbol type, and tells whether the symbol is an
opcode, pseudo-op, register, binary operator, etc.

The "c" field is the symbol subtype, the meaning of which depends on
the symbol type.  For opcodes, it tells what the operands should be,
for pseudo-ops and operators, it tells what the operation is,
and for registers it tells where the register may be used.
legal, and how it may be used.

(Updated 12-Jul-79 MFP)
5. The Format of an Output File:

The output file contains the assembled binary code for the target
microprocessor.  The default extension is .REL, though it bears little
semblance to a standard relocatable file.  First, it is in absolute
format.  Secondly, it is in a sort of hexadecimal ASCII text format.
There are consecutive records, each with the following format:

:<count><addr><zero><data><data>...<data><chxum><crlf>

With the exception of the leading colon, each eight-bit byte is represented
by two hexadecimal characters.  The meaning of each field is:

name	length		description

":"    1 char   This is a colon.  The loader for your microprocessor
		should ignore all characters before this.

count  1 byte   This is the number of bytes of data in this record.  Can
		be zero.

addr   2 bytes  This is the location of the first byte of data in this
		record.

zero   1 byte	This byte is always zero, probably reserved for a type field.

data   count    Consecutive bytes of data are to be loaded at
		consecutive memory locations.  This field can be null.

chxum  1 byte   This is the negated sum of all previous count, address,
		and data bytes in this record (taken modulo 256).  This
		means that as the loader for your microprocessor sums up
		every byte of this record as it is read in, when the
		checksum has been added in, the result will be zero.

(Corrected 12-Jul-79 MFP)
6. A Sample Run:

Here, the user input is shown in lower case, and the computer
response in upper case.   The text to the right of the
brokets ("<") is comment only, and isn't actually typed.

--------------------

.r micros		   < This is how you start the program
Swapping to SYS:MICROS.DMP
*test,test/c←foo(8080)	   < source file is FOO.MIC for 8080 processors,
NO ERRORS DETECTED	   < produces TEST.REL and TEST.LST.  The latter
			   < must now be run through the CREF program (see below)
PROGRAM BREAK IS 00D6	   < This is the highest address assembled into (in hex)
*↑C			   < You may specify another file to assemble, or CALL out
↑C
			   < Now we will run the CREF program to process TEST.LST
.r cref

*TEST←TEST		   < Looks for TEST.LST (in CREF format)
			   < Produces TEST.LST (in plain text format)
%CRFIDC IMPROPER INPUT DATA - CONTINUING   < This error can be ignored
[CRFXKC 5K CORE]
*↑C			   < This is how you get out of CREF (via CALL)
↑C

--------------------
7. Known bugs:

13-Jul-77 EJG	
A period in the middle of an identifier will cause a SAIL runtime CASE
indexing error (at least when using the 8080 symbol definition file).

27-Apr-79 ROB
Typing <ctrl><meta><linefeed> to the prompt gets into a loop; the program
starts to prompt infinitely.

05-May-79 ROB
If there are any errors in the source program, the CREF program looses
track of the symbols in the cross-reference section of the listing, and
outputs some sort of numeric representation of the symbols instead of the
symbol names.

05-May-79 DEK
Use of the IFL (and probably the others of that same family) as a label can
cause the assembler to go into an infinite loop.

11-May-79 ROB
The listing file created with the "/C" switch has some garbage which causes
CREF to complain (though apparently with no other ill effects).

12-Jul-79 MFP
The sym table entry for the 6800 AND operator was wrong (it did an OR).
I fixed it.